Tutorial 1: Introduction to WaveSongs

---

This tutorial guides users through analyzing, visualizing, and generating synthetic birdsongs using the wavesongs Python package, which is based on the motor gestures for birdsongs model developed by Prof. G. Mindlin.

If you are using Google Colab uncomment and execute the following cell:

Show code cell content Hide code cell content

# ! git clone https://github.com/wavesongs/wavesongs
# ! pip install wavesongs

# # enable hird party widgets (ipympl)
# from google.colab import output
# output.enable_custom_widget_manager()

# # correct ProjDirs parameters,
# audios = "/content/wavesongs/assets/audio"
# results = "/content/wavesongs/assets/audio/results"

Caution

If you encounter an error message, reset the kernel and run the above cell again. After that, everything should work successfully.

Then, follow the installation guide to set up the evironment and install the required libraries.

Libraries

Import the required classes and functions from wavesongs:

# Select matplotlib backend and enable interactive plots
# %matplotlib ipympl

from wavesongs.utils.paths import ProjDirs       # Manages project files
from wavesongs.objects.song import Song          # Song objects
from wavesongs.objects.syllable import Syllable  # Syllable objects
from wavesongs.utils import plots                # Plotting utilities
from wavesongs.utils.tools import get_roi        # Data extraction tools

To use objects like Syllable or Song, first define a project directory using a ProjDirs object. This object manages generated files such as images, audio files, and CSVs.

Next, create a Song instance with the project directory and a file name. In this tutorial, we use the audio file 574179401 - Zonotrichia Capensis.wav located at assets/audio/.

Once the song is defined, compute its acoustic features. You can specify parameters such as the Fast Fourier Transform (FFT) window and fundamental frequency (FF) method.

To display the spectrogram, use the plots module and the spectrogram_waveform function.

The name assigned to the song and syllables, “Copetón,” is the common name for Zonotrichia capensis in Colombia.

proj_dirs = ProjDirs(audios="../../../assets/audio", results="../../../assets/results")

# Define the song and compute its acoustic features
copeton_song = Song(proj_dirs, file_id="574179401")
copeton_song.acoustical_features(umbral_FF=1.4, NN=256)

# Display the song
plots.spectrogram_waveform(copeton_song, save=False)

# Play the song
copeton_song.play()

Long audio files can slow down plot response. A best practice is to define a region of interest (RoI), such as a complete birdsong.

To select a specific time interval, set select_time=True and define the start and end of the RoI.

# Define time interval for the RoI
tlim_roi = (0.7, 2.7)

copeton_syllable = Song(proj_dirs, file_id="574179401", tlim=tlim_roi)
copeton_syllable.acoustical_features(umbral_FF=1.4, NN=256, ff_method="yin", flim=(1e2, 2e4))

klicker_times = plots.spectrogram_waveform(copeton_syllable, tlim=tlim_roi,
                                           select_time=True, save=True)

Image save at ../../../assets/results/images/574179401-ZonotrichiaCapensis-Song.png

copeton_syllable.play()

This function returns an array of measurements, where each element is a vector containing time and frequency range values.

Warning

If no selection is made, an error will occur.

# data = get_roi(klicker_times)
# tlim, flim = data[0] # index = 0: first pair
# t0 = tlim[0] + copeton_syllable.t0_bs
# tend = tlim[1] + copeton_syllable.t0_bs
# print(f"Region of Interest: (tini = {t0:.4f} s, tend = {tend:.4f} s)")

# Define a syllable object within the selected RoI
tlim = (0.8802, 1.3010)
copeton_syllable_0 = Syllable(obj=copeton_syllable, tlim=tlim, type="intro-down", no_syllable="0")
copeton_syllable_0.acoustical_features(NN=256)

# Display the syllable's spectrogram
plots.spectrogram_waveform(copeton_syllable_0, ff_on=True, save=True)

Image save at ../../../assets/results/images/574179401-ZonotrichiaCapensis-0-intro-down

copeton_syllable_0.play()

# Write audio
copeton_syllable_0.write_audio()

Audio saved at ../../../assets/results/audios/574179401-ZonotrichiaCapensis-syllable-0.wav.

Further Lectures

For more details on birdsong modeling and bioacoustics, refer to the WaveSongs documentation and related scientific literature.

Applications

Some fields were we belive this package can contribute:

• Bioacoustic Research

• AI & Machine Learning

• Ecology & Conservation

• Neurobiology & Behavior

• Sound Synthesis & Engineering

• Education & Citizen Science

Conclusion

This tutorial introduced WaveSongs for bioacoustic analysis, covering setup, song processing, spectrogram visualization, and synthetic syllable generation. By following these steps, you can analyze bird vocalizations and optimize synthetic models for research or educational purposes.

Happy coding! 🎵🔬